docs(spec,i18n): stop naming the removed feature_flags settings namespace - #30647

📓 Docs Drift Check

⚠️ 3 changed file(s) yielded no anchor (packages/spec/src/kernel/index.ts, packages/spec/src/kernel/public-auth-features.ts, packages/spec/src/system/settings-manifest.zod.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

domain:spec#2 · os-sales · session_01L6bhgVugtCCwBs98FeR27P

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f1e4de5bd241aa4f7569580a535089706ce97443
Local-runs: none
Scope: packages/spec/src/kernel/index.ts, packages/spec/src/kernel/public-auth-features.ts, packages/spec/src/system/settings-manifest.zod.ts + packages/services/service-settings/src/manifests/index.ts, packages/services/service-settings/src/manifests/{mail,branding,localization}.manifest.ts, packages/services/service-settings/src/settings-service.types.ts (envKeyOf), packages/services/service-settings/src/settings-service.ts (effectiveEnvOverride), packages/spec/scripts/build-docs.ts, content/docs/references/system/settings-manifest.mdx, docs/adr/0007-settings-manifest-and-kv-store.md, .changeset/30282-feature-flags-namespace-text.md, ui/packages/i18n/src/tests/console-copy-system-noun-12956.test.ts (read for ③ only), PR #30595's ui/packages/i18n/src/locales/{zh-Hans,zh-Hant,pt-BR}.ts and zh-hant-generated.test.ts at 9b15e9ad (read for ③ only)

Independent reviewer, read-only: the net diff aad1603c..f1e4de5b (16 files, +96/−20), card #30282 with 6650008971 / 6650110716 / 6666332896 / 6668613789, and the head's check-runs. Timestamp 2026-11-05T20:44Z.

① Derived judgments

• Accept set: unchanged — right. The three spec hunks are comment text only: two // lines in the kernel/index.ts barrel, the module docblock of public-auth-features.ts, and line 14 of the module docblock of settings-manifest.zod.ts. No z.* call, no .describe(), no export, no type is touched (settings-manifest.zod.ts L74–L694 .describe() strings are all untouched; SettingsManifestSchema at L680 unchanged). The diff carries no change to packages/spec/api-surface/**, declaration-map/**, json-schema.manifest, liveness/** or docs/**, and check:generated reports all 14 generated artifacts current on this head (the dev's run, confirmed by the green Lint · docs & code guards / Build Docs check-runs). A git grep feature_flags of origin/main outside tests, CHANGELOGs, skills/** and release notes finds the three source sites, the mdx, two ADRs, one audit and one cache-doc example — no JSON Schema or API-surface artifact carries the string, so nothing else was owed regeneration.
• Published surfaces reached — named right. (a) settings-manifest.zod.ts L14 is NOT a .describe(); it is the module docblock, which packages/spec/scripts/build-docs.ts L511–L536 projects through modulePageDescription(...) into the mdx frontmatter description and the page's opening paragraph. The regenerated content/docs/references/system/settings-manifest.mdx L4 and L12 follow it exactly — this is the one generated artifact the change reaches, and it is in the diff. It is not projected into JSON Schema (that reads .describe() only). (b) The public-auth-features.ts docblock and the settings-manifest.zod.ts docblock are JSDoc-style leading comments of the next declaration (PublicAuthFeatureSurface, SpecifierType), so TypeScript's declaration emit (JSDoc-only comment retention) carries them into dist/kernel/index.d.ts / dist/system/index.d.ts under the tsup BUILD_DTS pass (packages/spec/tsup.config.ts L475–L487); no dist/ exists in the shared checkout and no published tarball is in node_modules, so this is read from the emitter's rule, not from an artifact. (c) The kernel/index.ts // note never ships: non-JSDoc comments are dropped from .d.ts. Net: one change reaches the docs site, up to two reach the published .d.ts text, none reaches a schema, a type, or the API surface.
• The PR body's account ("comments only, no schema/type/export change") matches the tree.

② Semver level

.changeset/30282-feature-flags-namespace-text.md: '@objectstack/spec': patch, '@object-ui/i18n': patch, body carries Clause-②: no and Metadata-protocol: none as line-initial declarations, and the PR body carries the same two lines. Against AGENTS.md Post-Task Checklist step 3: both packages are released (@object-ui/i18n is 18.3.0, not private; @objectstack/spec publishes dist/**/*.d.ts and the docs page), the diff publishes from each (a shipped UI string in ten packs; docblock text in the spec .d.ts and reference page), so skip-changeset would be wrong and patch is the level a none kind takes. No authorable key, export or value is added, removed or re-meant, so Metadata-protocol: none and Clause-②: no (no arm) are right. Check Changeset is green on the head. Level and declarations: right.

③ Boundary flags

• Addendum 6650008971 (settings-manifest.zod.ts L14 + mdx L4/L12): done — the example is replaced, not dropped, and the mdx is regenerated in the same PR (the addendum offered "drop the example"; replacing it with a registered namespace is at least as good, see ④).
• Triage 6650110716: p3, domain:spec, ui half named — both halves are in this PR under the one domain:spec#2 claim 6666332896, whose file surface this diff stays inside (three spec files, the mdx, the subtitle in every pack, one test, one changeset; nothing under skills/**, docs/adr/**, content/docs/releases/**, .claude/**, AGENTS.md).
• Dev report 6668613789, open_questions: [] — nothing to answer there.
• Serial note — PR feat(i18n)!: the Console's language packs follow the platform locale table, keyed by its tags, and Traditional Chinese (zh-Hant) ships #30595 still open (draft, head 9b15e9ad, 144 files): judged on its actual patches. It renames zh.ts → zh-Hans.ts (+5/−1, header lines only) and pt.ts → pt-BR.ts (+0/−0, pure rename), adds a generated zh-Hant.ts (5,164 lines) and zh-hant-generated.test.ts (byte-for-byte equality with gen-zh-hant.mjs over zh-Hans.ts), and changes line 54 only of console-copy-system-noun-12956.test.ts (builtInLocales.zh → builtInLocales['zh-Hans']). This PR edits line ~1921 of zh.ts / ~1882 of pt.ts and appends after line 69 of the same test. Either landing order merges cleanly: the renames are ≥99 % similar, so git's rename detection carries this PR's one-line hunks onto zh-Hans.ts / pt-BR.ts, and the two test-file hunks do not overlap. The new describe is key-agnostic (Object.entries(builtInLocales), floor ≥ 10), so it holds on eleven packs under the new keys. One consequence the dev's note does not name: zh-Hant.ts on feat(i18n)!: the Console's language packs follow the platform locale table, keyed by its tags, and Traditional Chinese (zh-Hant) ships #30595's head reads subtitle: '配置系統、整合與功能開關。' (OpenCC s2twp output), so whichever PR lands second ships a Traditional pack still promising feature flags until pnpm --filter @object-ui/i18n gen:zh-hant is re-run; feat(i18n)!: the Console's language packs follow the platform locale table, keyed by its tags, and Traditional Chinese (zh-Hant) ships #30595's own byte-for-byte test reds that state, so the regeneration is forced, but by feat(i18n)!: the Console's language packs follow the platform locale table, keyed by its tags, and Traditional Chinese (zh-Hant) ships #30595's guard, not this PR's. This PR's pin matches /功能开关/u (Simplified) and so does NOT catch the generator's 功能開關 — the PR body's "a zh-Hant pack that copies the old Chinese wording is caught" holds for a verbatim Simplified copy only. should-fix (lane seat's file, outside hits, not a FAIL): add /功能開關/u to FEATURE_FLAG_TERMS in ui/packages/i18n/src/__tests__/console-copy-system-noun-12956.test.ts L86–L96 so the pin holds the Traditional pack on its own merits.
• Dev's local exit 1 on ui/scripts/__tests__/date-only-zone-pins-10183.test.ts: that file is in the ui unit vitest project (ui/vitest.config.mts L409 scripts/**/*.test.ts), so the Test UI (n/16) shards on this head are its verdict, not the dev's control-worktree account. At this record's stamp the head's check-runs stood at 27 success, 7 skipped, 0 failed, 28 still running (all 16 Test UI shards, 8 Test Core shards, Build Core, Type Check UI, Build & E2E UI, Type Check · workspace). Every gate that has concluded is green; the dev's local red is answered by the Test UI shards when they conclude, and the lane's ACCEPT and the queue wait on them as on any PR. This verdict is on the hits files and does not turn on those shards; a red shard on this head re-opens ③, not ④.
• Dev's check:test-typecheck heap crash on first run: re-run green by the dev; CI's Type Check · debt ledger is green on the head. Not a diff property.

④ Design judgment

Every sentence of the new text, read against the live tree at origin/main aad1603c:

• "There is no central feature-flag namespace" — true. builtinSettingsManifests (packages/services/service-settings/src/manifests/index.ts L29) holds nine manifests: ai, auth, branding, company, knowledge, localization, mail, sms, storage (pinned at nine by settings-visibility-declaration.pin.test.ts L77, and settings-service.test.ts L51 pins that feature_flags is absent). The only other namespace: manifest literal in non-test source is lifecycle (packages/objectql/src/lifecycle/lifecycle-settings.ts L15). No manifest, builtin or plugin-registered, is a feature-flag namespace.
• "a setting a plugin reads is declared on that plugin's own settings manifest (SettingsManifestSchema, ADR-0007 …)" — true: SettingsService.registerManifest is the one door, and SettingsManifestSchema is the shape (settings-manifest.zod.ts L680). Naming it from the kernel barrel is fine; it lives under @objectstack/spec/system, and a reader grepping the symbol lands on it.
• "env-overridable via OS_{NAMESPACE}_{KEY}" — true, and I tried to break it. envKeyOf (settings-service.types.ts L643–L646) is 'OS_' + \${namespace}${key}`.replace(/[.-]/g, '').toUpperCase(). Its one runtime caller, effectiveEnvOverride (settings-service.tsL1393–L1395), readsthis.env[envName]for every registered key with no opt-in or allow-list, andthis.envdefaults toprocess.env(L929). So a reader who follows the docblock and setsOS_MAIL_SMTP_HOST sets a variable that is read; the only spelling nuance (./-→) is one an env-var name forces anyway. The pre-existing hazard is the ADR, not this text: docs/adr/0007-settings-manifest-and-kv-store.mdL326–L336 still spells the override as bareMAIL_SMTP_HOST/FEATURE_FLAGS_AI_ENABLED(noOSprefix) — a reader who follows the docblock's ADR citation instead of its own spelling sets a variable that is never read. That isdocs/adr/**`, outside this card's surface and the dev's permitted paths; noted below, not charged to this PR, whose own text gives the live spelling.
• "the capabilities a deployment advertises to clients are the PUBLIC_AUTH_FEATURES registry (public-auth-features.ts)" — true as the registry defines itself: it classifies every boolean flag plugin-auth's getPublicConfig() serves on /api/v1/auth/config features, with a key-set drift guard (public-feature-registry.test.ts) and the requiresFeature lowering in ui/action.zod.ts. Clients read the endpoint; the registry is the spec-side classification of what it carries, which is what a spec docblock should point at.
• public-auth-features.ts docblock: "NOT to be confused with a runtime setting — that is declared on the settings manifest of the plugin that reads it (ADR-0007), not in this registry; there is no central feature-flag namespace (… feat(spec)!: remove the dead static capabilities-descriptor cluster #3605)" — consistent with the barrel note and with the tree; the retained #3605 / FeatureFlagSchema history is unchanged and still correct (kernel/feature.zod.ts is absent on main).
• settings-manifest.zod.ts L14: "(e.g. mail, branding, localization)" — all three are registered builtins (mail.manifest.ts L46, branding.manifest.ts L64, localization.manifest.ts L34). Replacing rather than dropping the example keeps the docblock's teaching value, and the mdx follows it.
• Break attempts that failed: a reader looking for the retired feature_flags.ai_enabled / kanban_swimlanes / realtime_cursors / inline_comments has nowhere wrong to look, because Feature flags: all four toggles have no reader, so turning them on does nothing #30204's changeset records that none had a reader; a reader wanting a login-page gate is sent to the registry, which names its own consumers; a reader wanting a per-plugin toggle is sent to that plugin's manifest and the OS_ env form that envKeyOf actually produces.

Findings in hits: none must-fix, none should-fix. The three edits say what the tree does.

Out of scope, noted for a carrier: (1) ADR-0007 L326–L336 env-override table lacks the OS_ prefix envKeyOf produces (settings-service.types.ts L645) — a docs-only ADR amendment; (2) the should-fix on the ui pin in ③.

Implemented-by: claude/issue-30282-feature-flags-namespace-text
Reviewed-by: session_01L6bhgVugtCCwBs98FeR27P

VERDICT: PASS

Generated by Claude Code

domain:spec#2 · os-sales · session_01L6bhgVugtCCwBs98FeR27P

维护者速读

• 改了什么：设置中心的副标题在十种语言里都不再提“功能开关”，例如英文改为 “Configure your system and integrations.”。spec 里三段文档注释不再指向已删除的 feature_flags 设置命名空间和 OS_FEATURE_FLAGS_* 环境变量，改为说明插件的设置写在它自己的设置清单上（环境变量形如 OS_{NAMESPACE}_{KEY}），面向客户端的能力开关看 PUBLIC_AUTH_FEATURES。
• 为什么改：feature_flags 命名空间和它的设置页已经删除，副标题却还在承诺功能开关，管理员会去找一个不存在的页面；文档注释也会把读者引到一个不存在的清单和读不到的环境变量。
• 风险与回滚：只改文字。没有 key 增删，schema、类型、导出都没变。两个包各出 patch。回滚即 revert 本 PR。
• 先看：ui/packages/i18n/src/__tests__/console-copy-system-noun-12956.test.ts 新增的 describe → packages/spec/src/kernel/index.ts 和 public-auth-features.ts 的注释。
• 两分钟验证：pnpm --filter @object-ui/i18n exec vitest run src/__tests__/console-copy-system-noun-12956.test.ts，预期全过；把任一语言的副标题改回旧句，对应一条转红。
• 需要你做的：无，席位落地。
• 席位意见：接受。契约面达档复核 PASS（comment 6668918657，Head-sha f1e4de5b），没有 must-fix；一条 should-fix（pin 没收繁体“功能開關”）不采纳，理由见第 5 项。

席位核对

ACCEPT · head f1e4de5bd241aa4f7569580a535089706ce97443 · 2026-11-05T20:49Z

1. 形态：
   • draft，base main，正文 Fixes #30282，全文只有这一个闭合关键词。
   • 16 个文件都在认领 6666332896 的文件面内：三个 spec 文件、重新生成的 mdx、十个语言包里的副标题、一个测试、一个 changeset。
   • 没有改动其他 key 或语言字符串，也没碰代码、skills/**、content/docs/releases/**、docs/adr/**、.claude/**、AGENTS.md。
2. 前提实测：
   • 在 origin/main aad1603c 上，kernel/index.ts L20-22 还写着 feature_flags 设置清单和 OS_FEATURE_FLAGS_*，public-auth-features.ts L22 和 settings-manifest.zod.ts L14 还在举它作例子，十个包的副标题都承诺功能开关。
   • 复核在 main 上核过：builtinSettingsManifests 共 9 个命名空间，没有 feature_flags；mail、branding、localization 都已登记；envKeyOf 拼成 OS_ 加大写的 namespace_key。前提成立。
3. 门禁 check-runs：
   • head f1e4de5b 上读到 37 success、7 skipped、0 failure，另有 18 条仍在跑（Test UI / Test Core 分片等）。全部跑完且无红，才 pr_ready + automerge_enable。
   • dev 本地 date-only-zone-pins-10183.test.ts 的 exit 1 由 CI 的 Test UI 分片判定，该文件在 ui unit 项目里（ui/vitest.config.mts L409）。dev 的对照 worktree 在基点加本补丁上 29/29 通过。
   • 契约复核 6668918657 在 Served-tier: CONTRACT_REVIEW_TIER 下 PASS，Scope 覆盖三个 hits（kernel/index.ts、public-auth-features.ts、settings-manifest.zod.ts），以及设置服务的 envKeyOf / effectiveEnvOverride、内建清单和 build-docs.ts 的投影。
   • dev 本地 104 条派生门禁 --ran 0 NOT-MEASURED，只证本地子集；六条首轮 exit 3 是前置包没构建，构建后重跑都是 0。
   • 消融：de 副标题改回原句后 pin 1 条转红，还原后 blob 等于 HEAD。
4. 席位自读（TIER_DEFAULT，hits 之外的部分）：
   • 十个语言包：逐行读了 FROM → TO，每个包只删掉“功能开关”那一项，句子仍然通顺，语气与原句一致。
   • 测试：新 describe 枚举 builtInLocales 的每个包（≥10），每个包的副标题对照全部九种写法的术语；自检一条确认每个术语都能抓到它退役的原句。
   • mdx 是生成产物，两处与 L14 的新例子一致。dev 本地 check:generated 重跑 exit 0，head 上 Lint & Repo Gates 和 Build Docs 都是 success。
   • changeset 逐句核过：@objectstack/spec 和 @object-ui/i18n 都是 patch，Clause-②: no / Metadata-protocol: none，与认领一致；“No key is added or removed”和“No schema, type or export changes”都与 diff 一致。
5. 接受的偏差：
   • 复核 should-fix：FEATURE_FLAG_TERMS 只收简体 /功能开关/u，PR feat(i18n)!: the Console's language packs follow the platform locale table, keyed by its tags, and Traditional Chinese (zh-Hant) ships #30595 生成的 zh-Hant.ts 写的是 “功能開關”。不采纳：feat(i18n)!: the Console's language packs follow the platform locale table, keyed by its tags, and Traditional Chinese (zh-Hant) ships #30595 自带的 zh-hant-generated.test.ts 逐字节对照 zh-Hans.ts 的生成结果。两个 PR 不管谁后落地，繁体包只要还留着旧句，那条测试都会当场转红，逼着重新生成，不会悄悄合进去。为一条测试补正则挪 head，还要再复核一次，不划算。
   • PR 没设 assignee 和 reviewer，Tier S 不交人。
6. 范围外去向和 Skills-docs:：
   • 种类是 none，没有 (narrowing)，不欠 Skills-docs: 行。
   • 复核记下的范围外观察：docs/adr/0007-settings-manifest-and-kv-store.md L326-336 的环境变量示例（MAIL_SMTP_HOST、FEATURE_FLAGS_AI_ENABLED）没有 OS_ 前缀。dropped，原因：面向使用者的 content/docs/deployment/environment-variables.mdx L243 已写明 OS_<NAMESPACE>_<KEY>，ADR 只是设计记录里的旧示例，没有人在改它，修 ADR 也属 Tier H，说不出动手的人，所以不立卡。
   • 与 PR feat(i18n)!: the Console's language packs follow the platform locale table, keyed by its tags, and Traditional Chinese (zh-Hant) ships #30595 的串行：复核按两边的真实补丁核过，zh.ts → zh-Hans.ts、pt.ts → pt-BR.ts 的改名能带上本 PR 的单行改动，两边对测试文件的改动也不重叠，谁先落地都合得干净。后落地的一方重新生成 zh-Hant。
7. 落地条款：check-governed-merges.mjs --pr 30647 已在本 head 读过：16 个路径 0 个命中 governed 登记，116 行（+96 / -20）≤ 3000，属于 Tier S；落地前再读一次。CI 全绿后经 relay pr_ready + automerge_enable，跟到 MERGED，同一动作里摘 pm:dispatched。

Generated by Claude Code